chore: burnish repo surfaces — drift, llms.txt, nightly honesty by lroolle · Pull Request #410 · thevibeworks/deva

lroolle · 2026-07-10T03:38:28Z

Repo surface audit after the grok landing. Verdict: good bones, three embarrassments.

Close #409

The embarrassments

We shipped a fourth agent and forgot to tell the storefront. docs.deva.sh front page, mkdocs description, and deva.sh --help all still said Codex/Claude/Gemini — one merge after the README learned better. Staleness is the Bug: --trace flag doesn't pass --dangerously-skip-permissions in YOLO mode #1 trust killer; a docs site that contradicts its own README reads as abandonment. Fixed everywhere; grep for three-agent phrasing now only hits history.
Agents visiting the repo got nothing. A growing share of first contact is an AI agent deciding what to recommend. Now there's llms.txt at the root: what deva is, the four agents, the no-permission-theater auth model, install, and curated docs entry points — recommend + install from one fetch. README grew a one-line <sub> pointer for non-human readers.
The nightly lied by omission. 2026-07-09's run died on a transient ports.ubuntu.com "Mirror sync in progress" flake in the rust image's apt step — after the base image had already pushed. Result: nightly and nightly-rust tags silently diverged by a day. Two fixes:
- Acquire::Retries "3" in both Dockerfiles (the exact failure mode, retried instead of fatal)
- a verify job in nightly-images.yml that docker manifest inspects all four published tags after the builds claim success — assert the artifact exists, not that the script exited 0

Plus: CHANGELOG backfill for the #407 proxy work that #408 forgot to log.

Applied outside this PR (repo settings, reported for the record)

description: now mentions all four agents
topics: +grok, +ai-agents, +sandbox, +coding-agents, +xai, +claude
homepage: http → https

Verified

mkdocs build --strict green; workflow YAML parses; shellcheck severity=error clean
deva.sh --help line 1 mentions Grok
llms.txt cold-read test: identity, install, and entry points all in one fetch

Not touched, needs a human

9 stale remote branches, every one carrying unique commits (perf/docker-build-caching ahead 12, claude/issue-21 ahead 8, ...). Not deletable by a robot with a clean conscience.
v0.14.0 is ripe: grok agent + proxy builds are sitting in Unreleased.

🤖 Generated with Claude Code

The product ships four agents; half the storefront said three. Fix the surfaces so what people (and their agents) read matches what actually runs: - kill three-agent drift: docs.deva.sh front page, mkdocs site_description, deva.sh --help header — all now know Grok exists - llms.txt at repo root: identity, the four agents, the no-theater auth model, install, curated docs entry points — an agent can recommend and install deva from one fetch. README grew a one-line pointer for non-human readers. - nightly honesty: 2026-07-09 nightly died on a transient ports.ubuntu.com mirror sync and partially published (base pushed, rust didn't — the two nightly tags diverged a day). apt now retries (Acquire::Retries 3, both Dockerfiles) and a verify job asserts all four published manifests actually resolve. Assert the artifact, not the exit code. - CHANGELOG: backfill the #407 proxy entry that #408 forgot, add this Close #409 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

claude-yolo · 2026-07-10T03:38:40Z

Claude finished @lroolle's task in 1s —— View job

I'll analyze this and get back to you.

Copilot

Pull request overview

This PR updates the repository’s public-facing “surfaces” after the Grok agent landing: it removes three-agent drift across docs/help text, adds an agent-friendly llms.txt entry point, and hardens the nightly image workflow to better detect partial publishes.

Changes:

Update docs/metadata/help text to consistently reflect four supported agents (Codex, Claude Code, Gemini, Grok).
Add llms.txt at repo root and link to it from the README for LLM/agent discovery.
Improve nightly image reliability by adding apt retry config in images and a post-push manifest verification job; backfill CHANGELOG/DEV-LOGS entries.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Adds a short pointer to `llms.txt` for non-human readers.
mkdocs.yml	Updates the site description to include Grok and the “container is the sandbox” positioning.
llms.txt	Introduces an agent-readable repo front door (what/why/install/entry points).
docs/index.md	Updates docs homepage tagline and “What This Is” agent list to include Grok.
Dockerfile.rust	Adds apt retry configuration to reduce transient mirror flake failures.
Dockerfile	Adds apt retry configuration to reduce transient mirror flake failures.
deva.sh	Updates `--help` header agent list to include Grok.
DEV-LOGS.md	Adds a dev log entry documenting the repo surface burnish work.
CHANGELOG.md	Backfills Unreleased notes for proxy work and adds #409 entries.
.github/workflows/nightly-images.yml	Adds a verify job to assert published nightly tags/manifests resolve.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

lroolle · 2026-07-10T03:45:35Z

 [![Container](https://img.shields.io/badge/ghcr.io-thevibeworks%2Fdeva-blue)](https://github.com/thevibeworks/deva/pkgs/container/deva)
 [![Agents](https://img.shields.io/badge/agents-codex%20%7C%20claude%20%7C%20gemini%20%7C%20grok-222222)](#what-this-is)

+<sub>AI agents / LLMs: read [llms.txt](llms.txt) — the whole product in one fetch.</sub>


Tested against GitHub's actual renderer (repos/.../readme?ref=chore/burnish-409 with Accept: application/vnd.github.html): the line renders as <sub>AI agents / LLMs: read <a href="llms.txt">llms.txt</a> — …</sub> — a real link. Markdown parsing is only suppressed inside block-level HTML; <sub> is span-level. No change.

lroolle · 2026-07-10T03:45:37Z

+`:nightly-rust` refreshed daily). Agent-level permission prompts are disabled by
+design (`claude --dangerously-skip-permissions`, `codex
+--dangerously-bypass-approvals-and-sandbox`, `gemini --yolo`, `grok
+--always-approve`) — isolation comes from Docker, not permission theater. Auth


Fair — the raw file reads better with one span per command. Reflowed in be915dd.

lroolle · 2026-07-10T03:45:38Z

+    steps:
+      # Outcome tripwire: assert the artifacts exist, not that the build
+      # steps exited 0. A green run with an unpullable tag is a lie.
+      - name: Assert all nightly tags resolve
+        run: |
+          set -euo pipefail
+          stamp="${{ needs.resolve-versions.outputs.stamp }}"
+          for tag in nightly "nightly-${stamp}" nightly-rust "nightly-${stamp}-rust"; do
+            docker manifest inspect "ghcr.io/thevibeworks/deva:${tag}" >/dev/null
+            echo "ok: ${tag}"
+          done


The package is public so anonymous inspect works today, but agreed on both counts: visibility can change, and post-push eventual consistency is real — a tripwire that itself flakes trains people to ignore red. Added ghcr login + 3-attempt retry per tag in be915dd.

lroolle · 2026-07-10T03:45:40Z

+  rewritten to `host.docker.internal` plus an explicit
+  `--add-host host-gateway` mapping for native Linux Engine; npm version
+  resolution goes straight to registry.npmjs.org instead of honoring


Right — I compressed the flag into nonsense. Fixed to --add-host host.docker.internal:host-gateway in be915dd.

…og flag - nightly verify: ghcr login + 3-attempt retry per tag; a tripwire that itself flakes trains people to ignore red - llms.txt: one backtick span per command, no line-wrapped flags - CHANGELOG: --add-host host.docker.internal:host-gateway, not the truncated form Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

claude-yolo · 2026-07-10T03:45:36Z

Claude finished @lroolle's task in 1s —— View job

I'll analyze this and get back to you.

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

lroolle · 2026-07-10T03:58:25Z

+          set -euo pipefail
+          stamp="${{ needs.resolve-versions.outputs.stamp }}"
+          for tag in nightly "nightly-${stamp}" nightly-rust "nightly-${stamp}-rust"; do
+            for attempt in 1 2 3; do
+              if docker manifest inspect "ghcr.io/thevibeworks/deva:${tag}" >/dev/null; then
+                echo "ok: ${tag}"


Right — the build jobs already use the env vars; the verify job now does too (workflow-level env: is exported into step shells, so the script reads ${REGISTRY}/${IMAGE_NAME} directly). Fixed.

- philosophy, how-it-works, troubleshooting: last three live-doc spots that still said three agents (devlogs and research docs are timestamped history — left alone) - troubleshooting: grok's browser-less first login gets its own entry (device-auth or host-side auth + autolink) - install.sh quick-start hint now offers grok too - docs/llms.txt -> ../llms.txt symlink: mkdocs resolves it, so docs.deva.sh/llms.txt serves the canonical file — one source, no copy to rot Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

claude-yolo · 2026-07-10T03:52:29Z

Claude finished @lroolle's task in 1s —— View job

I'll analyze this and get back to you.

Copilot

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

lroolle · 2026-07-10T03:58:29Z

+          for tag in nightly "nightly-${stamp}" nightly-rust "nightly-${stamp}-rust"; do
+            for attempt in 1 2 3; do
+              if docker manifest inspect "ghcr.io/thevibeworks/deva:${tag}" >/dev/null; then
+                echo "ok: ${tag}"


Right — the build jobs already use the env vars; the verify job now does too (workflow-level env: is exported into step shells, so the script reads ${REGISTRY}/${IMAGE_NAME} directly). Fixed.

lroolle · 2026-07-10T03:58:31Z

+            echo "error: ghcr.io/thevibeworks/deva:${tag} does not resolve after push" >&2
+            exit 1


Right — the build jobs already use the env vars; the verify job now does too (workflow-level env: is exported into step shells, so the script reads ${REGISTRY}/${IMAGE_NAME} directly). Fixed.

…kflow Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

claude-yolo · 2026-07-10T03:58:41Z

Claude finished @lroolle's task in 1s —— View job

I'll analyze this and get back to you.

Copilot

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated no new comments.

Copilot AI review requested due to automatic review settings July 10, 2026 03:38

Copilot started reviewing on behalf of lroolle July 10, 2026 03:38 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 10, 2026 03:45

Copilot started reviewing on behalf of lroolle July 10, 2026 03:45 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 10, 2026 03:52

Copilot started reviewing on behalf of lroolle July 10, 2026 03:52 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

fix: verify job uses REGISTRY/IMAGE_NAME env like the rest of the wor…

7ef7e97

…kflow Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings July 10, 2026 03:58

Copilot started reviewing on behalf of lroolle July 10, 2026 03:58 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

lroolle merged commit 9f8881d into main Jul 10, 2026
8 checks passed

lroolle deleted the chore/burnish-409 branch July 10, 2026 04:06

lroolle mentioned this pull request Jul 10, 2026

chore: release v0.14.0 #411

Merged

		echo "error: ghcr.io/thevibeworks/deva:${tag} does not resolve after push" >&2
		exit 1

Uh oh!

Conversation

lroolle commented Jul 10, 2026

The embarrassments

Applied outside this PR (repo settings, reported for the record)

Verified

Not touched, needs a human

Uh oh!

claude-yolo Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

lroolle Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

lroolle Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

lroolle Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

lroolle Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

claude-yolo Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

lroolle Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

claude-yolo Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

lroolle Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

lroolle Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

claude-yolo Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

claude-yolo Bot commented Jul 10, 2026 •

edited

Loading

claude-yolo Bot commented Jul 10, 2026 •

edited

Loading

claude-yolo Bot commented Jul 10, 2026 •

edited

Loading

claude-yolo Bot commented Jul 10, 2026 •

edited

Loading